Configuring Application Servers
Configuring application servers requires that the following be stored in XFAppServerConfig.xml:
-
The path to the file share root folder that will serve as a workspace for the application server.
-
The pool of database server connections, schema names and server connections for the Framework and State databases.
All other configuration values can use standard default values.
Using the Server Configuration Tool
-
Open the OneStream Server Configuration Tool.
-
Select File > Open Application Server Configuration File and browse to the default XFAppServerConfig.xml in the application server’s virtual directory.
TIP: Create a central location accessible for all server configurations in which to house this file. For example, C:\OneStreamShare\Config
-
When the file is open, define the following settings to configure the application server:
Application Server Configuration Settings
Remote Editing
Remote Editing allows adjusting Application Server Configuration setting access for Administrators and advanced IT persona. It is enabled by default but can be adjusted by Customer Support in the following manners:
-
Disable Full Feature by XML/App Config
-
Disable sections by XML/App Config
-
Disable property changes
-
Number of Days to Retain System Config History: Set the number of days to retain the system config history.
-
Can Edit selections: When True, users can make changes to the settings in the application. When False, modifying settings will no longer be available in the UI.
-
Use Edited selections: When True, the user-defined settings apply. When False, the default settings from the configuration file apply.
-
Can Add Database Server Connections: When True, users can add Custom Database Server Connections. When False, users are cannot add Custom Database Server Connections.
OneStream Environment
Define the following settings to customize your environment.
-
Environment Name and Color:Enter the name to be displayed (in white) for the environment. You can enter up to 150 characters. Specify a provided environment color or enter a hex value to display the name on a colored background. For example:
-
Can Use Client Updater:True enables the Client updater to upgrade a user’s version of Excel Add-In. False disables upgrades to Excel using the Client update. If disabled, users get a message indicating functionality was disabled by their System Administrator.
-
Can Use Administrator User: True activates the generic Administrator user account. False disables the Administrator logon. If the other Admin accounts were deleted, set this to True to support logon.
-
Use Detailed Logging: False omits internal error language and information from the error log.
-
Enable Help:Select True to display a help icon that launches the official documentation set. Select False to not display a help button.
-
Enable File Share Uploads:True enables authorized users to upload or edit files or folders in the File Share using the OneStream File Explorer. When False, users and Administrators can only browse, and not upload or edit files and folders. Users get a security error when writing or editing files or folders using API or another method.
Logon Agreement Type and Message:To display a specific message after a user logs on, selectCustomand enter the message text.
Environment Monitoring
Use Environment Monitoring settings to define the real time update frequency, and the KPIs and metrics to monitor. These metric categories help you manage and optimize applications and the application environment:
-
Environment
-
Application server
-
Database server
-
Server set
Use the Environment page to evaluate and monitor the environment, isolate bottlenecks, look at properties and configuration changes, and scale in/out application servers and database resources.
This section is used to specify how often metrics are collected and what metric types are collected:
URL for the Automatic Recycle Service
Used to specify the address of the recycle management service. The protocol for the address should be set to however the service is deployed (https or http) and the port (default is 50002). The asterisk will force the service to use the fully qualified domain name of the executing server.
Number of Running Hours Before Automatic Recycle
Default is 24, which means once a day, the server will recycle. Automatic Recycling allows Application Servers a chance to recycle, which is a recommended practice. These first four settings control this behavior.
Start Hour for Automatic Recycle (0 to 24 UTC)
Default is 5, which means 05:00 UTC time. This is the earliest time in a day when a server can automatically recycle. It is best to set this and the End Hour to be a range of time with the lowest amount of Application Server activity.
End Hour for Automatic Recycle (0 to 24 UTC)
Default is 7, which means 07:00 UTC time. This is the latest time in a day when a server can automatically recycle.
Maximum Number of Minutes to Pause Before Automatic Recycle
Default is 30. This means that when it is time to recycle a server automatically, it will first pause from accepting more server tasks, but allow for existing assigned tasks to complete processing for 30 minutes before recycling. If there are no active tasks for this server, it will recycle when the time comes.
Active Check Update Interval (seconds)
The system is designed to be pro-active and to check for any internal issues. This setting determines how often the system will check for table fragmentation and database deadlocks.
Metric Update Interval (seconds)
The Metrics are collected on a timer using this setting. To minimize database access and to maximize performance, some metrics are collected on every iteration and some will skip one or more iteration based on the metric collection iteration count settings that have been assigned to each metric. For example, if this property is set to 30 (seconds) and the “Collect Environment CPU Metrics” is set to “Every2Iterations” then the system will collect metrics every 60 seconds. If the property is set to “Always” the system will collect at every iteration, “Never” will never collect, “Once” will only collect upon server initiation. Also, the user can minimize database writes by using the global settings in the Application Server in the OneStream Server Configuration Utility.
Server Heartbeat Update Interval (seconds)
Used to specify how often each server updates its record that it is alive and responding to user input.
Collect Environment CPU Metrics
How often to collect environment CPU metrics.
Collect Environment Task Metrics
How often to collect environment task metrics (i.e; running tasks, Queued Tasks …).
Collect Environment Login Metrics
How often to collect environment user login metrics.
Collect Server Set CPU Metrics
How often to collect Server Set CPU metrics.
Collect Server Set Task Metrics
How often to collect Server Set task metrics (i.e; running tasks, Queued Tasks …).
Collect Server Disk Metrics
How often to collect server disk metrics (i.e; Average Disk read/write per sec…).
Collect Server Memory Metrics
How often to collect server memory metrics (i.e; Available mbytes…).
Collect Server Network Card Metrics
How often to collect server network card metrics.
Collect SQL CPU Metrics
How often to collect SQL Server CPU metrics.
Collect SQL Page Metrics
How often to collect SQL Server Page caching metrics (i.e; Page Life Expectancy…).
Collect SQL Memory Metrics
How often to collect SQL Server CPU metrics.
Collect SQL Connection Metrics
How often to collect SQL Server connection metrics (i.e; Number of connections…).
Collect SQL Query Metrics
How often to collect SQL Server Query metrics (i.e; Number of Deletes/Inserts…).
Collect SQL File Metrics
How often to collect SQL Server File growth metrics.
Collect SQL Elastic Pool CPU Metrics - Azure SQL
How often to collect SQL Server Elastic Pool CPU metrics (i.e; Number of connections…).
Collect SQL Elastic Pool DTU Metrics - Azure SQL
How often to collect SQL Server Elastic Pool DTU metrics (i.e; Number of connections…).
Collect SQL Elastic Pool Storage Metrics – Azure SQL
How often to collect SQL Server Elastic Pool Storage metrics (i.e; disk storage usage…).
Collect SQL Elastic Pool Workload Metrics - Azure SQL
How often to collect SQL Server Elastic Pool Workload metrics.
SQL Blocking Timeout Interval (Minutes)
Checks the SQL Blocked Items Timestamp. If the Timestamp is greater than “SQL Blocking Timeout Interval (minutes), ” a warning is logged.
Fragmentation Iteration Count
Default is 600 (minutes). Used for fragmentation check, every 10 hours if this field is set to 600. This is used to determine how often the database tables are fragmented.
Fragmentation Percent Threshold
Default is 90. Used for fragmentation threshold check in percent.
Detailed Logging
If true, then log whenever we enter and exit the metric collection and the Active System check.
Number Hours to Retain Offline Servers
Default is 1. Remove offline servers from the heartbeat table after certain number of hours.
Task Load Balancing
Default settings for Task Load Balancing for larger jobs like consolidation and data management. Application servers utilize queuing and smart load balancing to run that task on the appropriate application server. Task queueing and smart load balancing will prevent more than one processor-intensive task from running on the same server at the same time. When an asynchronous task is started (i.e., a task that uses the progress bar), it can be initialized in a Queued state before it starts its work in its Running state. The queued state takes very little application server resources. The algorithm keeps the task in the Queued state until all other queueable tasks have completed on that application server or until the CPU is low enough to run the task. There are also settings that can be configured to cause queued tasks to be automatically run if too much time elapses.
Maximum Queue Processing Interval (seconds)
Default is 10. Used to specify how often the queue will look for new jobs to execute.
Maximum Average CPU Utilization
Default is 70. Used to specify the maximum CPU utilization before a task is queued to a server but not executed till the CPU drops below that maximum.
Maximum Queue Time (minutes)
Default is 30. Used to specify the max queued time before a job is executed.
Number of Past Metric Readings for Average CPU
Default is 2. Used to specify the number of past metric reading used to calculate the average CPU utilization.
File Share Root Folder
To set the file share root folder property, type in the path to the file share folder, or copy and paste the path from Windows Explorer.
NOTE: File Share Root Folder might have a default directory defined as C:\OneStream\File Share\. This directory is not created. Please define the File Share Root Folder directory. Grant the system user NT AUTHORITY\NETWORK SERVICE full access to this folder.
File Share Batch Harvest Root Folder
Used to define a separate folder path for the Batch Harvest folder. Azure users who do not have access to the Azure folder can use this field to identify a folder where they can place their files for batch harvest.
NOTE: If you specify a separate path, the default folder will not be used.
Business Rules Assembly Folder
Used by Application Servers to reference the location of DLL files stored in a common Network Share Folder.
Business Rules Default Access Group
Default is Administrators. The access group for new Business Rules.
Business Rules Default Maintenance Group
Default is Administrators. The maintenance group for new Business Rules.
User Inactivity Timeout in Minutes
Used to identify the number of minutes a user has before their OneStream session times out while they are on a page in XF, or in Excel, without taking action.
Task Inactivity Timeout in Minutes
Used to identify the number of minutes a task in user cancelled status, or sitting in the queue waiting to be processed, has before being timed out.
Specify Log Retention Information
To set the log retention properties in days, type the number of days that the organization wishes to ensure logs are retained. If the delete activity or error logs buttons are used in OneStream, the logs will be cleared with the exception of the current number of days specified.
Log Retry Errors
PDF Embedded Fonts to Remove
Embedding fonts in a PDF Report Book significantly increases the size of the PDF file. Use this property to specify the fonts to not embed to reduce the size of PDF files and control the resolution during Report Book PDF generation. For multiple fonts, use a semicolon separated list.
The default setting is: Arial; Calibri; Segoe UI; Tahoma; Times New Roman; Verdana.
NOTE: This is for Report Books only.
Security
The Security section includes settings for Security, External Identity Providers, and Native Authentication.
Security
Whitelisted Domains: The Whitelisted Domains setting gives you the option to control the URLs and domains allowed to be referenced. You can update this setting with the following options:
-
AllowAll (default): This option will allow all http and https formatted domains.
-
DenyAll: This option will deny all URLs and domains. This option is recommended if there are concerns about the security of platform download features.
-
Enter specific domains, URLs, or wildcard matches to accept.
If the Whitelisted Domains field is empty (displays Collection) or displays Default, it will default to AllowAll. If the OneStream Application Server Configuration file is manually updated to remove the Whitelisted Domains field, it will default to AllowAll.
IMPORTANT: Regardless of the option selected, only http and https formatted domains can be referenced. References to non-http and non-https file schemes are not allowed.
To add an option for Whitelisted Domains:
-
In the Application Server Configuration file, click the ellipsis to the right of Security.
-
In the Security dialog box, click the ellipsis to the right of Whitelisted Domains.
-
In the Whitelisted Domains dialog box, click the + icon.
-
Update the Domain field with the selected approach:
-
Type AllowAll to allow all http and https formatted domains.
-
Type DenyAll to deny all URLs and domains.
-
Or, enter an absolute domain, an absolute URL, or a wildcard match using an * (for example, https://*.onestream.com or https://*.onestream.com/api/*) to allow specific URLs and domains.
IMPORTANT: If you add specific URLs or domains, only those identified URLs or domains will be allowed. All others will be denied.
-
-
Click the OK button.
NOTE: If you are adding specific domains, URLs, or wildcard matches to accept, follow this process to add as many as needed.
-
Save changes and reset IIS.
To remove an option for Whitelisted Domains:
-
In the Application Server Configuration file, click the ellipsis to the right of Security.
-
In the Security dialog box, click the ellipsis to the right of Whitelisted Domains.
-
In the Whitelisted Domains dialog box, select the option from the list on the left and click the - icon.
-
Click the OK button.
-
Save changes and reset IIS.
External Authentication Providers
You can configure authentication with external identity providers. To configure, click the ellipsis to the right of External Authentication Providers.
NOTE: When upgrading OneStream from a version prior version, note that the Windows Section of the external authentication provider may have been enhanced to support SSL enabled MSAD. As part of this change, any prior MSAD authentication providers will need to be transferred to the updated Windows Section of the external authentication provider entry. The Domain Name should be verified and entered in the Name of Account Store field and the appropriate binding options and type of account store should be specified.
In the External Authentication Providers dialog box, click +.
Create a name for the provider and complete the information based on the installation. The final configuration is then performed in the security section of the individual user profile. See Authentication.
NOTE: Comma-separated values (group names) can be entered in the Security Group Names field. A user must belong to any of the groups listed before OneStream will authenticate the user with MSAD. Security groups are also still needed in OneStream.
NOTE: Windows Authentication mechanism has been enhanced to support SSL enabled MSAD. See below for an example of default configuration values.
Name of Account Store: The domain or server name for domain context types, the machine name for machine context types, or the name of the server and port hosting the ApplicationDirectory instance.
Name of Account Store Container:The container on the store to use as the root of the context. All queries are performed under this root.
Server Binding Options: A combination of one or more ContextOptions values specifying the options used to bind to the server. Use one of the options from the drop-down menu or, if UseCombinedContextOptions is specified, enter multiple comma-separated values in the Combined Multiple Server Binding Options field. For a detailed description of these options, see Appendix: Context Option Values To Use With Active Directory + SSL.
Type of Account Store: Specifies the type of store to which the principal (user) belongs. Possible values are ApplicationDirectory (represents the AD LDS store), Domain (represents AD DS store), and Machine (represents SAM store). Defaults value is Domain.
NOTE: OneStream’s implementation of MSAD and LDAP authentication allows for the use of a single username and password when prompted to log into OneStream.
Native Authentication
See Authentication for information about setting up native authentication.
Control the standards for creating and updating passwords by defining the minimum and maximum character length, variety of characters, expiration dates, and maximum invalid logon attempts. If a positive number is provided for the Maximum Invalid Logon Attempts field and a user exceeds the number, their account will be disabled. After an administrator re-enables their account, the user will be required to change their password.
NOTE: Similarly, the administrator’s account can also be disabled if the maximum invalid logon attempts value is exceeded.
Azure Configurations (Azure-only or if Elastic Pool Being Used)
Azure Subscription Settings
The Azure subscription settings must be filled in, as they are used for login and retrieve Azure settings and data. In version 5.0 this is used to retrieve Elastic Pool metrics.
Cache
Reserved Memory (GB)
The reserve memory must be large enough to hold all non-analytic cached items, such as metadata, workflow, stage processing. If total system memory usage is consistently high and gets above 90%, reserve memory should be increased because non-analytic memory consumption is larger than the reserve and virtual memory pressure grow. This property is a string that contains a number for GB or a percentage of total RAM. If a percentage is specified, and after it is converted, the minimum is 4GB and the maximum is 256 GB. If a number is specified, the minimum is 0GB and the maximum is 256 GB.
Databases
Specify Database Information For the application server to connect to a database server, define one or more database connections to which the server can connect. Database connections can be imported from an xml file containing encrypted connection strings created using OneStream Database Configuration Tool or connection strings can be created directly in the OneStream Server Configuration Tool.
Importing Encrypted Database Connections
To import connections produced by the OneStream Database Configuration Tool, open the OneStream Server Configuration Tool and click the Tools menu and select the Import Database Server Connections option. Now browse for the encrypted database connections xml file produced using the OneStream Database Configuration Tool. After the connections have been imported, be sure to name each connection so that it can be referenced in the configuration process.
Database Server Connection Settings
Changes need to be made to the Database Server Connections for users to create and change data in additional database tables. These settings are used by some of the OneStream MarketPlace Solutions such as Specialty Planning and Reconciliation Control Manager.
Select the Database Server Connections field and click the ellipsis to launch these settings.
Azure Database Connection Settings
Azure Elastic Pool Max DTU Setting
This is a fail-safe setting that the user can’t set the DTU setting above this point.
Azure Elastic Pool Min DTU Setting
This is a fail-safe setting that the user can’t set the DTU setting below this point.
Elastic Pool Name
The name of the elastic pool used with this database connection.
Azure Resource Group
The resource group name that the elastic pool is in.
Azure Service Level Objective
The service level used. This setting is used to create application on Azure.
Azure SQL Edition
The Azure SQL Server edition used.
Azure SQL Scaling Type
This feature will be available in a future release.
Manual, Business Rule, and ManualAndBusinessRule. The type of scaling that is used to scale in/out the SQL Server eDTUs.
Azure SQL Server Name
The name of the SQL Server database. This setting is used to create application on Azure.
Azure SQL Storage Max Size
This is used to specify the database storage size when creating a database on Azure.
Azure SQL System Business Rule Name
This feature will be available in a future release.
If SQL Scaling Type is set to Business Rule, this setting must be set to a Business Rule that is used to Scale Out and Scale In. The Environment metrics and the database metrics are passed to this rule to properly determine the eDTU scaling. See System Extender Business Rules in the Design and Reference Guide.
Access Group for Ancillary Tables
This should be set to a group who will edit records.
Maintenance Group for Ancillary Tables
This should be set to a group who will create the tables.
Other settings highlighted need to be set to True in order to execute table creation via the MarketPlace Dashboards.
Defining Database Connections Manually
Database server connections are defined and named using the Database Server Connection Collection Editor which is opened by clicking the button in the right column of the Database Server Connections property.
The Database Server Connection Collection Editor allows database connections to be added or removed and the creation of meaningful names for the connections. The name of the connection is important because it acts as an abstraction layer to which the application server can interact. This allows the database administrator to change the connection string for a name database server connection without affecting the application server or any other component that may rely on the named connection.
In addition, name database connections can help organize development, test, and production environments because relevant names can be assigned to a database connection based on its environment. Named connections appear as a list in the OneStream user interface during the process of creating new applications. This feature allows OneStream administrators to simply pick database connections to use for the new application database. If the Allow Database Creation Via UI property in the Application Server Configuration is set to False, this means none of the attached database servers are setup to allow new application creation which will then disable the Create New Application Database icon.
Enabling Remote Editing
Enable your database server connections for remote editing from the configuration file.
-
Enable Remote Editing: When True, users can make changes to the settings in the application. When False, modifying Enable Remote Editing settings will no longer be available in the UI.
-
Use Remote Editing Settings: When True, the user-defined settings apply. When False, the default settings from the configuration file apply.
Specify Database Connections and Schemas
Once database connections have been imported or defined manually, they can be used in conjunction with the schema name to define full connection information for the Framework and State databases.
Define Framework Database Connection
In order to define the Framework database connection, specify the database server connection name that contains the Framework database, and then specify the name of the Framework database schema on the server.
Server Sets
NOTE: A server should only be in one server set.
A server set should contain all servers, which will perform that set’s unique combination of behaviours.
Used to create Server Sets for server grouping.
Azure - This feature will be available in a future release.
These settings apply only when running in OneStream Cloud.
Azure Resource Group Name
This feature will be available in a future release.
The Azure resource group name for the Server Set.
Azure Scale Set Name
This feature will be available in a future release.
The Azure scale set name in the resource group.
Can Stop or Start Servers
This feature will be available in a future release.
If true, then the user can stop and start the server from the Environment page.
Maximum Capacity
This feature will be available in a future release.
A failsafe setting specifying the maximum number of servers that can be scaled up to.
Minimum Capacity
This feature will be available in a future release.
A failsafe setting specifying the minimum number of servers that can be scaled down to.
Scaling Type
This feature will be available in a future release.
Specify whether this Scale Set is scaling at all or doing so manually, using a Business Rule, Automatically or both manually and a Business Rule. If Business Rule-based, see next property.
System Business Rule Name
This feature will be available in a future release.
If Scale Set is scaling using a Business Rule, then the Business Rule name needs to be specified. See System Extender Business Rules in the Design and Reference Guide.
Behaviors
Process Queued Consolidation Tasks
If set to true, then this server can process Consolidation tasks.
Process Queued Data Management Tasks
If set to true, then this server can process Data Management tasks.
Process Queued Stage Tasks
If set to true, then this server can process Stage tasks.
Queued Tasks Require Named Application Server
If set to True, this server will only run tasks that are assigned to it. If set to False, server names will be ignored so jobs will run on an available server.
NOTE: This behavior only applies to customers in an on-premises environment with a server name that is known.
General
Name
Server Set name.
Server Name for Standard Server Sets (Supports *? Wildcards)
Specify the Server names if we are using the Standard Server Set Provider type. See next property.
Sever Set Provider
Specify whether we are using the “Standard”, “Azure”, or “External” provider type.
Processing
Can Change Queueing Options on Servers
Specify whether the queueing options of a specific server can be changed. If the Value is set to True, it will allow the administrator to change the queueing behavior of a specific server as it relates to queueing Stage, Consolidation and Data Management tasks.
Can Pause or Resume Servers
If set to true, then the user can pause and/or resume the server from the Environment page.
Can Recycle App Pool on Severs
If set to true, then the user can recycle the app pool from the Environment page via the Reset IIS button.
Integration Settings
These properties enable the modification of the Stage Summary Rows and Stage Load Values. These settings allow optimization and tuning of the Workflow Import behavior related to the summarization of records for the StageSummaryTargetData table to be performed on the application or database server. The summarization method of using the Application Server is determined by the calculated Summarized Row Ratio (SRR). The Summarized Row Ratio configuration property sets the threshold for the calculated SSR. Having less than 100k records, or high summarization, which is a calculated SRR less than the property, or default .65, will utilize the Application server. All Append, use of multiple Source ID's or a calculated SRR greater than the property value, or default .65, will use the Database server. The calculated SSR is done on subsequent Stage Import loads and stored in the Framework MetricsValue table.
Minimum Data Record Count
The default is 100,000. This determines the minimum data record count to trigger Database Server Processing. This threshold determines the use of the Application or Database server.
Summarized Row Ratio
The default is Greater than .65. This is the ratio of Total Summarized Rows/Total Number of Rows Imported. Subsequent loads generate a new Summarized Row Ratio. This threshold is used to evaluate the calculated SSR for the Application or Database servers.
Always Use Database Server
The default is “False”. When set to “True”, the feature that allows for Application Server Processing in Stage Import and Load during the Workflow processing is turned off. This disables the summarization of the Application server, Minimum Data Record Count and Summarized Row Ratio no longer apply.
Task Activity
Task Activity is used to capture log information for Books and Quick Views to analyze data analysis performance.
Log Books
When set to True (default), a log is created in Task Manager when the items are included as Task Activity steps for that specific book. The intention of this feature is to verify entries in the Task Activity grid and the settings in the configuration file work as expected.
Log Cube Views
When set to True, a log is created in Task Manager when a Cube View is opened, a report is run or an export to Excel is completed in the data explorer. The intention of this feature is to analyze data analysis performance.
Log Quick Views
When set to True, a log is created in task manager when a new Quick View is created or when rows/columns are shifted/moved around. The intention of this feature is to analyze data analysis performance.
IMPORTANT: Quick Views exceeding 5000 cells will be logged in Task Activity even if Log Quick Views setting is set to False, enabling you to cancel the task if needed.
Threshold for Logging Get Data Cells (count)
This logs the calls to GetDataCells and GetDataCellsUsingScript. It includes context information such as the Excel file name or the Cube View name. It only creates logs if the number of Data Cells being requested is equal to or greater than the value provided in this field.
Zip File Protection
Maximum Zip Archive Entry Threshold: Set the maximum number of files that can be included in a zip file. The default value is 1,000.
Maximum Zip File Extraction Size (MB): Set the maximum extraction size in MB (sum of all files) allowed in a zipped file. The default is 2,000.
Maximum Zip File Compression Ratio (N:1): Set the ratio between the uncompressed and compressed size (zip file size divided by packed size). The default is 800.
Sharing One Configuration File for All Application Servers
All OneStream application servers can share a single configuration file if desired. This makes controlling server behavior more centralized and reduces configuration time.
Sharing a configuration file is a simple process. Follow the standard application server configuration process on one server and then copy the configuration file to a file share that all application servers can read. This shared folder will then need to be referenced by each application server in its ASP.Net Web.Config file.
Setting a Reference for the Configuration File Share Folder
Open the OneStream Server Configuration Tool on each application server, click the File menu, and select Open ASP.Net Configuration File. Next, open to the Web.Config for the application server. This file is located in application server’s virtual directory root folder (C:\Program Files\OneStream Software\OneStreamAppRoot\OneStreamApp\Web.Config).
Once the file is open, set the Configuration Folder property value equal to the configuration file share folder, save the configuration file and restart IIS.